Structure Variables

Structure variables have the type code IDL_TYP_STRUCT. They also have the IDL_V_STRUCT bit set in their flags field. The value.s field of such a variable contains a structure descriptor defined by the IDL_SREF structure:

typedef struct {

IDL_ARRAY *arr; /* ^ to IDL_ARRAY containing data */

void *sdef; /* ^ to structure definition */

} IDL_SREF;

The arr field points at an array block, as described in Array Variables. It is worth noting that in the definition of the IDL_ALLTYPES union (described in The IDL_VARIABLE Structure), the arr field is a pointer to IDL_ARRAY, while the s field is an IDL_SREF, a structure that contains a pointer to IDL_ARRAY as its first member.

The resulting definition looks like:

union {

IDL_ARRAY arr;

struct {

   IDL_ARRAY arr;

   void *sdef;

} s;

} value;

Due to the way C lays out fields in structs and unions, value.arr will have the same offset and size within the value union as value.s.arr. Therefore, it is possible to access the array block of a structure variable as var->value.arr rather than the more correct var->value.s.arr. Avoid using this shorthand, because it is not strictly correct usage and because we reserve the right to change the IDL_SREF definition in a way that could cause the memory layout of the ALLTYPES union to change.

Creating Structures

The actual structure definition is accessed through the sdef field, which is a pointer to an opaque IDL structure definition. Although the implementation of structure definitions is not public information, they can be created using the IDL_MakeStruct() function from a structure name and a list of tags:

void *IDL_MakeStruct(char *name, IDL_STRUCT_TAG_DEF *tags)

name

The name of the structure definition, or NULL for anonymous structures.

tags

An array of IDL_STRUCT_TAG_DEF elements, one for each tag. The result from this function can be passed to IDL_ImportArray() or IDL_ImportNamedArray(), as described in Creating an Array from Existing Data.

IDL_STRUCT_TAG_DEF is defined as:

typedef struct {

char *name;

IDL_MEMINT *dims;

void *type;

UCHAR flags;

} IDL_STRUCT_TAG_DEF;

name

Null-terminated uppercase name of the tag.

dims

An array that contains information about the dimensions of the structure. The first element of this array is the number of dimensions. Following elements contain the size of each dimension.

type

Either a pointer to another structure definition, or a simple IDL type code cast to void (e.g., (void *) IDL_TYP_BYTE).

flags

A bit mask that specifies additional characteristics of the tag. Allowed values are:

• IDL_STD_INHERIT: Type must be IDL_TYP_STRUCT. This flag indicates that the structure is inherited (inlined) instead of making it a sub- structure as usual.

The following example shows how to define an anonymous structure. Suppose that you want to create a structure whose definition in the IDL language is:

{TAG1: 0L, TAG2: FLTARR(2,3,4), TAG3: STRARR(10)}

It can be created with IDL_MakeStruct() as follows:

static IDL_MEMINT one = 1;

static IDL_MEMINT tag2_dims[] = { 3, 2, 3, 4};

static IDL_MEMINT tag3_dims[] = { 1, 10 };

static IDL_STRUCT_TAG_DEF s_tags[] = {

{ "TAG1", 0, (void *) IDL_TYP_LONG},

{ "TAG2", tag2_dims, (void *) IDL_TYP_FLOAT},

{ "TAG3", tag3_dims, (void *) IDL_TYP_STRING},

{ 0 }

};

 

typedef struct data_struct {

IDL_LONG tag1_data;

float tag2_data [4] [3] [2]; IDL_STRING tag_3_data [10];

} DATA_STRUCT;

static DATA_STRUCT s_data;

void *s;

IDL_VPTR v;

 

/* Create the structure definition */

s = IDL_MakeStruct(0, s_tags);

 

/* Import the data area s_data into an IDL structure,

   note that no data are moved. */

v = IDL_ImportArray(1, &one, IDL_TYP_STRUCT,

   (UCHAR *) &s_data, 0, s);

Accessing Structure Tags

Given an opaque IDL structure definition, you can determine the offset of the data and a description of its size and form (scalar, array, etc) for a given tag. IDL_StructTagInfoByName() returns this information given the name of the tag. IDL_StructTagInfoByIndex() does the same thing, given the numeric index of the tag. They are essentially the same routine, although IDL_StructTagInfoByIndex() is slightly more efficient:

IDL_MEMINT IDL_StructTagInfoByName(IDL_StructDefPtr sdef,

   char *name, int msg_action, IDL_VPTR *var)

IDL_MEMINT IDL_StructTagInfoByIndex(IDL_StructDefPtr sdef,

   int index,int msg_action, IDL_VPTR *var)

where:

sdef

Structure definition for which offset is needed.

name (IDL_StructTagInfoByName)

Name of tag for which information is required.

index (IDL_StructTagInfoByIndex)

Zero based index of tag for which information is required.

msg_action

The parameter that will be passed directly to IDL_Message() if the specified tag cannot be found in the supplied structure definition.

var

NULL, or the address of an IDL_VPTR to be filled in with a pointer to the variable description for the specified field.

On success, these functions return the data offset of the tag. On error, if the resulting call to IDL_Message() returns to the caller, a -1 is returned. The data offset can be added to the data pointer of an IDL variable of this structure type to obtain a pointer to the actual data for that tag.

If the tag is successfully located and the var argument is non-NULL, the IDL_VPTR it points at is filled in with a pointer to an IDL_VARIABLE structure that describes the type and organization of the tag. It is important to understand that this IDL_VARIABLE does not contain any actual data (or in the case of an array tag, a valid data pointer). Hence, the data part of the IDL_VARIABLE description should be ignored.

Determining the Number Of Structure Tags

The IDL_StructNumTags() function returns information on how many tags a structure definition has:

int IDL_StructNumTags(IDL_StructDefPtr sdef)

where:

sdef

Structure definition for which offset is needed.

Determining the Names Of Structures and their Tags

The IDL_StructTagNameByIndex() function returns the name of a specified tag from a structure definition, and optionally the name of the structure:

char *IDL_StructTagNameByIndex(IDL_StructDefPtr sdef, int index,

   int msg_action, char **struct_name)

where:

sdef

Structure definition for which name information is needed.

index

Zero based index of tag within the structure.

msg_action

The parameter that will be passed directly to IDL_Message() if the specified tag cannot be found in the supplied structure definition.

struct_name

NULL, or the address of a character pointer (char *) to be filled in with a pointer to the name of the structure. If the structure is anonymous, the string “<Anonymous>” is returned.

On success, a pointer to the tag name is returned. On error, if the resulting call to IDL_Message() returns to the caller, a NULL pointer is returned.

All strings returned by this function must be considered read-only, and must not be modified by the caller.